API-er, kaffe og feilfri frokost

Tydelige forventninger er en undervurdert luksus

En god frokost trenger ikke mange ingredienser. Den trenger tydelige forventninger. Brødet bør være brød, kaffen bør være kaffe, og egget bør ikke plutselig introdusere et nytt autentiseringskrav idet du minst venter det. På samme måte er et godt API sjelden det med flest endepunkter. Det er det du forstår uten å måtte åpne en arkeologisk utgravning av Slack-tråder.

API-design handler i stor grad om å holde løfter. Hvis et felt heter createdAt, bør det være et tidspunkt da noe ble opprettet, ikke datoen noen sist så på det, eller en streng som av og til er null fordi tirsdag var komplisert. Hvis en ressurs ikke finnes, skal svaret være forutsigbart. Ikke 200 med et tomt objekt og et passiv-aggressivt felt kalt success: false. Det er ikke fleksibilitet. Det er dokumentasjon som har sagt opp uten å levere inn nøkkelbrikken.

Den beste API-dokumentasjonen svarer på spørsmål før de blir dyrere enn en dobbel espresso: Hva sender jeg? Hva får jeg tilbake? Hva skjer når det feiler? Hvordan paginerer dette? Hvilke ting er stabile, og hvilke ting er fortsatt litt på ferie? Eksempler bør være ekte nok til at utviklere kan bruke dem, men enkle nok til at ingen trenger å tolke dem som moderne poesi.

Det samme gjelder versjonering. Å endre et felt fra streng til objekt fordi «det er mer framtidsrettet» kan være sant på papiret. I praksis er det som å bytte ut kaffekoppen til alle på kontoret med en suppeskål før morgenmøtet. Mulig, men neppe verdsatt. Små, kompatible forbedringer er vakre. Brudd bør varsles, forklares og helst komme med en migreringssti som ikke involverer månefaser.

Feilfri frokost finnes kanskje ikke. Det gjør heller ikke feilfrie API-er. Men begge blir betraktelig bedre når du respekterer mennesket på andre siden: den sultne personen før første møte, eller utvikleren som bare prøver å hente en liste med brukere før deploy-vinduet lukkes.